.pl 29.7c
.\" $Id: sm2awk.1,v 1.3 2004/07/11 08:04:47 bhepple Exp $
.TH SM2AWK 1 "Tue Oct 27 1992" "\&\(co Bob Hepple"
.UC 4
.nr pl 5i
.SH NAME
sm2awk \- convert
.B "Screen Manager"
forms definitions into
.BR awk (1)
report writer scripts.
.SH SYNOPSIS
.B sm2awk
[
.B \-p
]
.I screenfile
.SH DESCRIPTION
.B sm2awk
reads the
.B "Screen Manager"
file description in
.I screenfile
and writes a boilerplate
.BR awk (1)
script to stdout.
The intent is that this boilerplate is edited into
a useful
.BR awk (1)
script which can be run against the data for a meaningful report.
.LP
While
.BR awk (1)
tends to use cardinal numbers to specify fields (as in \fI$1, $2\fR
etc.),
.B sm2awk
attempts to use the field names assigned in the
.B "Screen Manager"
description file
.I screenfile
and creates a mapping table of the form:
.LP
.RS
\fIName=$1\fR
.br
\fICompany=$2\fR
.br
\fIetc...\fR
.RE
.LP
in the preamble.
The script subsequently uses the symbolic rather than
the numeric fields resulting in a much more readable and maintainable
.BR awk (1)
script.
.LP
It would be nice if
.BR awk (1)
had an include facility so that these field-name to field-number
tables could be separately maintained but it doesn't so that's the end
of that! As field names and positions in the data change and fields are added and
removed, it is therefore up to the user to check that any old
.BR awk (1)
reports are updated with the new field descriptions.
Too bad.
.LP
The
.B -p
option instructs
.B sm2awk
to include the background fields from the
.I screenfile
to be output as well as the data fields.
.SH EXAMPLES
In theory, if the data is in \fIproject.txt\fR and the
.B "Screen Manager"
file description is in \fIproject.dat\fR (and is correct!) the
commands:
.LP
.RS
\fIsm2awk project.dat >project.awk\fR
.br
\fIawk -f project.awk <project.txt >project.new\fR
.RE
.LP
will recreate the original data file as \fIproject.new\fR.
There may
be trivial differences in the treatment of empty fields at the end of lines,
and in whitespace for files with whitespace as the field delimiter.
.SH FILES
.TP
.B *.dat
Conventionally,
.B "Screen Manager"
files have a '.dat' extension although this is not required.
.TP
.B *.txt
Data files - again, this convention is not enforced.
.SH ENVIRONMENT
.SH "SEE ALSO"
Postscript version of these man pages which have screenshots -
probably in /usr/share/doc/scrmgr-X.Y.
.LP
.so sm2awk.lst
.SH BUGS
.B "Screen Manager"
can cope with a wider range of characters in field names than
.BR awk (1),
e.g. it can
accept the minus sign \fB'\-'\fR in a field name.
.B sm2awk
attempts to convert fieldnames appropriately.
.LP
.BR awk (1)
cannot easily cope with fixed length fields (i.e. those with a length
specified as negative in
.BR smcreate )
so these are best avoided
if
.BR awk (1)
is to be used.
.SH AUTHOR
Bob Hepple <bhepple@freeshell.org>
.SH COPYRIGHT
Copyright \(co 1991-2002 Bob Hepple
